/**
Interfaces for working with the Hub manager

A Protocol is a Service that registers itself as supporting connecting to central hubs
A Connection is an object that associates connection settings to a name
A HubStatus is the object that collects all the information used in a Connection
	  
*/

namespace java hydrap2p.hub
namespace csharp hydrap2p.hub

include "service.thrift"

exception NameTaken {
	1: string hubtype,
	2: string name
}
exception NameNotFound {
	1: string hubtype,
	2: string name
}
exception DuplicateProtocol {
	1: string hubtype
}
exception ProtocolNotConnected {
	1: string hubtype,
	2: string name
}

struct HubStatus {
	1:string hubtype,		// a registered Protocol that knows how to make this connection
	2:string name,			// a name for this connection object
	3:map<string,string> params,	// connection settings that mean something to the Protocol
	4:bool autoconnect,		// whether this connection should be connected as soon as the Protocol shows up
	5:bool connected,		// whether this connection is connected
	6:string status,		// a pretty connection status string
}

service HubListener extends service.Service {
	/**
	Notify this listener that a new Hub connection has been added
	*/
	oneway void connectionAdded(1:HubStatus status),

	/**
	Notify this listener that the parameters of this Hub connection have changed
	*/
	oneway void connectionChanged(1:HubStatus status),

	/**
	Notify this listener that this Hub connection has been removed from the list of Hub connections
	*/
	oneway void connectionRemoved(1:HubStatus status),

	/**
	Notify this listener that this Hub connection has changed connection status
	*/
	oneway void connectionConnected(1:HubStatus status),
	
	/**
	Notify this listener that a new Protocol has appeared
	*/
	oneway void protocolRegistered(1:string name),
	
	/**
	Notify this listener that a protocol has disappeared
	*/
	oneway void protocolUnregistered(1:string name)
}

service HubProtocol extends service.Service {
	/**
	Instruct this Hub Protocol to attempt to connect to this connection
	*/
	void connect(1:string name, 2:map<string,string> params),

	/**
	Instruct this hub Protocol to disconnect from this connection
	*/
	void disconnect(1:string name)
}

service HubManager extends service.Service {
	/**
	Add a hub connection to the list of available connections
	*/
	void addConnection(1:string hubtype, 2:string name, 3:map<string,string> params, 4:bool autoconnect) throws (1:NameTaken ouch),

	/**
	Change the parameters of a hub connection
	*/
	void changeConnection(1:string hubtype, 2:string name, 3:map<string, string> params, 4:bool autoconnect) throws (1:NameNotFound missing),

	/**
	Remove a hub connection
	Also tells the hub protocol
	*/
	void removeConnection(1:string hubtype, 2:string name),

	/**
	Get the status of a hub connection
	*/
	HubStatus getStatus(1:string hubtype, 2:string name),

	/**
	Get the statuses of all the hub connections
	*/
	list<HubStatus> getStatuses(),
	
	/**
	Get a list of available protocols
	*/
	list<string> getProtocols(),

	/**
	Attempt to connect to a hub
	*/
	void connect(1:string hubtype, 2:string name) throws (1:NameNotFound name, 2:ProtocolNotConnected protocol),

	/**
	Disconnect from a hub
	*/
	void disconnect(1:string hubtype, 2:string name),

	/**
	*******
	Callbacks from Hub Protocols
	*******
	*/

	/**
	Register a hub protocol
	*/
	void registerProtocol(1:string hubtype, 2:service.ServiceLocation location) throws (1:DuplicateProtocol ouch),

	/**
	Unregister a hub protocol
	*/
	void unregisterProtocol(1:string hubtype),

	/**
	Notified when the connection status of a hub changes
	*/
	void connected(1:string hubtype, 2:string name, 3:bool connected, 4:string status)

}


